Coding Standards for R and Python

Tidyverse Style Guide

Some of its syntax suggestions:

Tidyverse Style Guide

A simple example:

# Ignoring TidyVerse Style Guide ----
myVector=c(10,20,30)

myCalc=function(x,Multiplier){x*Multiplier}

myCalc(myVector,Multiplier=10)


# Applying TidyVerse Style Guide ----
my_vector <- c(10, 20, 30)

my_calc <- function(x, multiplier) {
  x * multiplier
}

my_calc(my_vector, multiplier = 10)

PEP 8

Some of its requirements:

PEP 8

A simple example:

# Multiplies input by a multiiplier
def Multiply(inputVal,MultiplierVal=10):
 return inputVal*MultiplierVal

def multiply(input_val, multiplier_val=10):
    """Multiplies an input by a multiplier.

    Args:
        input_val: The input value.
        multiplier_val: The multiplier value.

    Returns:
        The product of the input value and the multiplier value.
    """

    return input_val * muliplier_val

There is a separate PEP for docstrings see PEP 257

Tools to help

• Code formatters

  • reformat code to match a particular style.
  • mostly spacing, indentation, line length, not renaming variables!

• Code linters

  • flag potential bugs, poor practice, style violations.
  • linters do not change the code, but inform of problems.
    
    

  Tool Type	R Packages	Python Packages
  Formatter	styler, formatR	autopep8, Black
  Linter	lintr	Flake8, pylint

styler and lintr

Use these tools from the R Studio Addins menu once the packages are installed.

In R Studio any issues flagged by lintr are shown in a Markers tab:

Unfortunately R Studio does not have on save option for running formatters. See pre-commit hook if using Git.

Black and pylint

After installing the packages with pip or conda can apply formatting or linting checks using a terminal:

However, an easier way to use these tools is within an IDE such as VS Code, PyCharm.

Formatting and linting in VS Code

• VS Code has code formatter and linter extensions for Python.

• Linting and formatting tools can be configured to run every time save.

• VS Code also has a useful extension for automatically generating function docstrings.

Pre-commit Hooks

• Part of a git workflow. Pre-commit hooks ensure code meets certain standards before it is committed.
• Checks are specified in a .pre-commit-config.yaml file in the code repository.
• These checks can include the formatting and linting tools described previously.
• For Python see pre-commit.
• For R it’s a bit more complicated to setup. Python pre-commit must also be installed. The R package precommit has a useful setup article.

Continuous Integration (CI)

• Automated builds and tests are run when code changes are pushed to a central repository.
• GitHub Actions might be used to run a specific formatter or linter as part of a CI pipeline.

• GitHub Actions can be configured to run when opening a GitHub Pull Request.
• GitHub Actions can be configured so cannot merge a branch unless the checks pass.
• This is an advanced topic. Other CI tools are available Travis CI, Jenkins.

Creating Documention

Both R and Python have specific ways to document functions (and classes in Python).

• Python Docstrings are wrapped in """. See PEP 257.
• Docstrings go directly under def function_name:

For example:

def multiply(input_val, multiplier_val=10):
  """Multiplies an input by a multiplier.

  Args:
    input_val: The input value.
    multiplier_val: The multiplier value.

  Returns:
    The product of the input value and the multiplier value.
  """
  return input_val * muliplier_val

• With Python can see the documentation for a function using print(my_function_name.__doc__)

Function Documentation R

• For R functions add Roxygen comments to document them.
• Using R Studio insert a Roxygen template (R Studio > Code menu > Insert Roxygen Skeleton).

#' My calculation
#'
#' @param x numeric vector or number to be multiplied.
#' @param multiplier the scaler value to multiply x by.
#'
#' @return scaled value
#' @export
#'
#' @examples
#' my_calc(c(1, 2, 3), 10)
my_calc <- function(x, multiplier) {
  x * multiplier
}

• When developing an R package roxygen2::roxygenise() is used to generate the documentation .Rd files from the roxygen comments.
• See documentation section of the Tidyverse Style Guide and also in the R Packages online book.